home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / tcdebug.zip / TCDEBUG.DOC < prev    next >
Text File  |  1988-05-08  |  38KB  |  1,255 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                                             May 7, 1988
  9.  
  10.                              TCdebug Version 1.01
  11.  
  12.                     (C) Copyright 1987 by L. David Baldwin.  
  13.                              All Rights Reserved.
  14.  
  15.   Further copyright information given below
  16.  
  17.  
  18.   OVERVIEW
  19.  
  20.   TCdebug is an experimental source code debugger for use in debugging Turbo 
  21.   C (tm) Programs on the IBM-PC (tm).  Its goal is to allow source code 
  22.   debugging in all of Turbo C's memory models and with most of the possible 
  23.   compile and link options.  TCdebug allows you to:
  24.  
  25.        1.  View your source code (and, optionally, the assembly language 
  26.            code) while debugging.
  27.        2.  Trace the operation of your program by source code lines or by 
  28.            assembly language instructions.
  29.        3.  Insert breakpoints in your program by function name, by line 
  30.            number, or hexadecimal address.
  31.        4.  Examine (and change) simple global variables by symbolic name.  
  32.            Local variables may also be examined and changed, but require that 
  33.            the proper displacement on the stack be known. 
  34.        5.  Set up a Watch window to keep continuous tabs on a variable.
  35.        6.  Profile your program to find those portions which contribute most 
  36.            to the execution time.
  37.  
  38.   TCdebug is designed exclusively for debugging Turbo C programs.  It should 
  39.   not be used on programs generated by other compilers.
  40.  
  41.  
  42.   SYSTEM REQUIREMENTS
  43.  
  44.        1.  An IBM-PC, AT, or compatible.  Screen compatibility is a must.
  45.        2.  PC-DOS 2.0 or above.
  46.        3.  Approximately 135k more memory than would normally be required to 
  47.            run the program to be tested.
  48.  
  49.  
  50.   PREPARATION
  51.  
  52.   TCdebug requires that a Map file for your program be present to supply 
  53.   information on the program symbols and line number locations.  When 
  54.   compiling and linking with TC, the options can be set with O/C/C/L and 
  55.   O/L/M/P.  With TCC use -M and -y.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                                       1
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.   It is also highly desirable that the program to be tested be compiled with 
  75.   the 'standard stack frame' option on.  Using TC, set this option with 
  76.   O/C/C/S.  With TCC, use -k (The manual says -Y but that's apparently a 
  77.   typo).
  78.  
  79.   When starting a debugging session, the following files should be on the 
  80.   default drive:
  81.  
  82.     PROG.EXE    (or, optionally, .COM for the Tiny Model)
  83.     PROG.MAP    the map file
  84.  
  85.   Any C source files which will be accessed during the debugging session 
  86.   should also be on the default drive or on Paths specified in the DOS PATH.
  87.  
  88.  
  89.  
  90.   OPERATION
  91.  
  92.   TCdebug may be started by entering the filename of the program to be 
  93.   debugged and any parameters which it requires on the command line, as:
  94.  
  95.     TCdebug PROG <other stuff>
  96.  
  97.   Here, PROG is the name of the program to be tested with EXE being the 
  98.   default extension.  <other stuff> will be passed on to PROG as its command 
  99.   line when execution begins.  If TCdebug is called without parameters, a 
  100.   request will be made for them.
  101.  
  102.   When execution begins, TCdebug loads the Map file, the EXE file and reports 
  103.   some facts about the program.  Note should be made of whether pointers are 
  104.   regarded as Near or Far by default as this will be important when 
  105.   displaying pointers later.
  106.  
  107.   After "hitting any key", the program is executed to "main()" and the 
  108.   debugging screen appears.  The debugging screen is divided into two parts.  
  109.   The lower section is the command and data section.  The '*' is a prompt for 
  110.   one of the commands described later.  The top part of the screen displays 
  111.   the program source code text which at this point will be centered at the 
  112.   first statement in main().  Source code line numbers appear at the left 
  113.   with the current line (the one to be executed next) being highlighted.
  114.  
  115.   Dividing the two portions of the debugging screen is a line which shows the 
  116.   name of the source file presently displayed.
  117.  
  118.   Two keys which can be tried at this point are the F9 and F10 keys.  The 
  119.   F9 key toggles into and out of the assembly mode.  When in assembly mode, 
  120.   the assembly language instructions of the program are displayed with the 
  121.   source code lines interspersed.  The F10 key toggles between the debugger 
  122.   screen and the screen which receives program output.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                       2
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.   SPECIAL KEYS FOR VIEWING TEXT
  141.  
  142.   The following keys may be used to change the text being displayed:
  143.  
  144.        Pg Up
  145.        Pg Dn       Move the display up or down one page.
  146.  
  147.        ^Pg Up
  148.        ^Pg Dn      Move to the start or end of the current file.
  149.  
  150.        Up arrow
  151.        Down arrow  Scroll up or down one line.
  152.  
  153.        ^Left Arrow  (with Scroll Lock on)
  154.        ^Right Arrow (with Scroll Lock on)
  155.                    Scroll horizontally left and right.
  156.  
  157.        F9 key      Toggle in and out of assembly mode.
  158.  
  159.        F10 key     Toggle between the debug screen and the screen
  160.                    of the program under test.
  161.  
  162.        Alt-U       Move dividing line up one line.
  163.        Alt-D       Move dividing line down one line.
  164.  
  165.   Note that the toggling of the Scroll Lock key effects the action of some of 
  166.   the special keys.  The text display may also be changed using the View 
  167.   command described later.
  168.  
  169.  
  170.   COMMAND EDITOR
  171.  
  172.   Commands are entered at the '*' prompt.  When entering commands, the 
  173.   following keys may used to edit the command:  (They perform the same 
  174.   functions as they do in the Turbo C editor.)
  175.  
  176.        ^A,^S,^D,^F,^G,^T,^H,^V,^Y,LFARW,RTARW,^LFARW,^RTARW,
  177.        Ins, Del, Backspace
  178.  
  179.   The Insert mode (default) is indicated by a slightly fatter cursor.  The 
  180.   cursor is normal in the Overwrite mode.
  181.  
  182.   In addition, a stack of the last 6 commands (those having more than 3 
  183.   characters) is maintained.  The F3 key accesses the stored commands from 
  184.   the most recent to the oldest and the F5 key accesses them in the reverse 
  185.   order.  These old commands may be used as is or may be modified by editing 
  186.   them.
  187.  
  188.   Note that commands are not acted upon until the Enter key is hit.  (The 
  189.   cursor does not have to be at the line end to enter the command.)
  190.  
  191.  
  192.  
  193.  
  194.                                       3
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.   COMMAND PARAMETERS
  207.  
  208.   TCdebug uses one or two letter commands.  The command is often followed by 
  209.   one or more parameters.  Parameters are delimited from the command and each 
  210.   other using spaces.  The one exception to this is the format parameter 
  211.   which is preceded by a comma.  The parameters which may be used are:
  212.  
  213.     <Symbol>
  214.        A C source code symbol representing a function name or variable as 
  215.        appropriate.  The leading underbar added by the compiler has been 
  216.        stripped off, so symbols are entered exactly as used in the source 
  217.        program.  Case is significant (unless the non case sensitive link 
  218.        option was selected).
  219.  
  220.        The special symbols, _AX, _AL, _BX, etc. may be used to refer to the 
  221.        hardware registers.
  222.  
  223.        A special symbol, rtn (or RTN), refers to the return address of the 
  224.        current function.  For this symbol to function reliably, the program 
  225.        should be compiled with the 'standard stack frame' option on.  
  226.        Currently, this symbol can only be accessed if the current CS:IP is on 
  227.        an exact source line number.
  228.  
  229.          Examples:
  230.            V rtn    Find out who called this function.
  231.            G RTN    Execute the remainder of this function, return to caller.
  232.  
  233.  
  234.     <Line Number>
  235.        Line numbers are entered as <filename>\<number> as:
  236.            myprog.c\345
  237.  
  238.        In most cases, the <filename> part can be dropped.  An entry of the 
  239.        form
  240.  
  241.            \345
  242.  
  243.        implies line number 345 in the currently displayed source file.  
  244.        (Currently, the '\' also may be dropped and a simple decimal entry will 
  245.        do.  However, the '\' may be required in future versions.)
  246.  
  247.     <Hexaddress>
  248.